街景服务  

Google 街景提供整个覆盖区域内以指定道路为中心的 360 度全景视图。街景的 API 覆盖范围与 Google 地图应用 (https://maps.google.com/) 的覆盖范围相同。要获取街景当前支持的城市列表，请访问 Google 地图网站。

以下显示了一个示例街景图像。

Maps JavaScript API 提供了街景服务，用于获取和处理 Google 地图街景中使用的图像。浏览器原生支持该街景服务。

尽管街景可在独立 DOM 元素内使用，但其在表示地图上的位置时最有用。地图上会默认启用街景，并且街景小人控件会集成到导航（缩放和平移）控件中。您可以在地图的 MapOptions 中将 streetViewControl 设置为 false，以便隐藏该控件。您还可以通过将 Map 的 streetViewControlOptions.position 属性设置为新的 ControlPosition 来更改街景控件的默认位置。

借助街景小人控件，您可以直接在地图内查看街景全景图片。当用户点击并按住街景小人时，地图会进行更新，在支持街景的街道周围显示蓝色轮廓，从而带来与 Google 地图应用类似的用户体验。

用户在街道上放置街景小人标记时，地图也会进行更新，以显示所指示位置的街景全景图片。

通过使用 StreetViewPanorama 对象可支持街景图像，该对象提供了街景“查看器”的 API 接口。每张地图均包含一幅默认的街景全景图片，您可以通过调用地图的 getStreetView() 方法对其进行检索。当您通过将地图的 streetViewControl 选项设置为 true 在地图上添加街景控件时，会自动将街景小人控件与此默认街景全景图片相关联。

您也可以创建自己的 StreetViewPanorama 对象，然后将地图的 streetView 属性显式设置为该构造对象，从而将地图设置为使用该对象而非默认的街景全景图片。如果您想修改默认行为，例如在地图和全景图片之间自动共享叠加层，则可能希望覆盖默认全景图片。（请参阅下文的街景内的叠加层）。

您也可能希望在单独的 DOM 元素（通常为 元素）内显示 StreetViewPanorama。只需在 StreetViewPanorama 的构造函数内传递相应 DOM 元素即可实现此目的。要想获得最佳图像显示效果，我们建议的最小图像尺寸为 200x200 像素。

注意：尽管街景功能设计为与地图结合使用，但这并非强制性要求。您也可以在不使用地图的情况下独立使用街景对象。

StreetViewPanorama 构造函数还可让您使用 StreetViewOptions 参数设置街景位置和视角。您可以在构造完成后对该对象调用 setPosition() 和 setPov() 来更改其位置和 POV。

街景位置会定义图像的相机焦点位置，但不会定义该图像的相机朝向。为此，StreetViewPov 对象会定义以下两个属性：

StreetViewPov 对象最常用于确定街景相机的视角。您还可通过 StreetViewPanorama.getPhotographerPov() 方法确定拍摄者的视角，该视角通常是汽车或街景三轮车所面向的方向。

以下代码将显示一张初始视角为芬威球场的波士顿地图。选择街景小人并将其拖放到地图上某个支持的位置可更改街景全景图片：

在支持设备屏幕方向事件的设备上，用户可以通过 API 随设备的移动改变街景视角。用户可通过移动设备环视四周。这叫做动作跟踪或设备旋转跟踪。

作为应用开发者，您可以按照以下方式更改默认行为：

隐藏或显示动作跟踪控件。默认情况下，支持动作跟踪的设备上会显示该控件。用户可以点按该控件来开启或关闭动作跟踪功能。请注意，如果设备不支持动作跟踪，无论 motionTrackingControl 的值是什么，该控件都不会显示。

以下示例将同时停用动作跟踪功能和动作跟踪控件。在此情况下，用户无法开启动作跟踪功能：

要了解动作跟踪的实用效果，请在移动设备（或任何支持设备屏幕方向事件的设备）上查看以下示例：

查看示例

默认的 StreetViewPanorama 对象支持在本地显示地图叠加层。叠加层通常在“街道级别”显示，并锚定在 LatLng 位置。（例如，显示标记时，其尾部会锚定于街景全景图片内相应位置的水平面。）

目前，街景全景图片支持的叠加层类型仅限于 Marker、InfoWindow 和自定义 OverlayView。您在地图上显示的叠加层可显示在街景全景图片上，方法是将全景图片视为 Map 对象的替代项，调用 setMap()，并以参数形式传递 StreetViewPanorama（而非地图）。同样，通过调用 open()，然后传递 StreetViewPanorama() 而不是地图，也可以在街景全景图片中打开信息窗口。

此外，在创建使用默认 StreetViewPanorama 的地图时，只要与地图关联的街景全景图片可见，则在地图上创建的任何标记都会自动与其共享。要检索默认街景全景图片，请对 Map 对象调用 getStreetView()。请注意，如果您将地图的 streetView 属性显式设置为您自己构造的 StreetViewPanorama，则会覆盖默认全景图片。

以下示例将显示一些标记，用于表示纽约市阿斯特广场周围的不同位置。将显示画面切换到街景可显示 StreetViewPanorama 内显示的共享标记。

在街景之间导航或操纵其朝向时，您可能希望监控指示 StreetViewPanorama 状态变化的若干事件：

以下代码展示了如何处理这些事件以收集关于底层 StreetViewPanorama 的数据：

当显示 StreetViewPanorama 时，全景图片上会默认显示各种控件。您可以通过将 StreetViewPanoramaOptions 中的相应字段设置为 true 或 false 来启用或停用这些控件：

以下示例将更改关联街景内显示的控件并移除该视图的链接：

您可能希望以编程方式确定街景数据的可用性，或返回有关特定全景图片的信息，而无需直接处理地图/全景图片。您可以使用 StreetViewService 对象来实现此目的，该对象提供了一个连接 Google 街景服务内所存储数据的接口。

由于 Google Maps API 需要调用外部服务器，因此对街景服务的访问是异步进行的。因此，您需要传递一个回调方法，以便在请求完成时执行。该回调方法会对结果进行处理。

您可以使用 StreetViewPanoRequest 或 StreetViewLocationRequest 向 StreetViewService 发出请求。

如果指定了可唯一标识全景图片的参考 ID，使用 StreetViewPanoRequest 的请求会返回相应的全景图片数据。请注意，这些参考 ID 仅在该全景图像的生命周期内保持稳定。

使用 StreetViewLocationRequest 的请求会使用以下参数在指定位置搜索全景图片数据：

函数 getPanorama() 需要一个在通过街景服务检索到结果后执行的回调函数。此回调函数会按照先数据后代码的顺序返回 StreetViewPanoramaData 对象内的一组全景图片数据，以及一个表示请求状态的 StreetViewStatus 代码。

StreetViewPanoramaData 对象规范包含关于街景全景图片的元数据，具体形式如下：

请注意，此数据对象本身并不是 StreetViewPanorama 对象。要使用此数据创建一个街景对象，您需要创建一个 StreetViewPanorama 并调用 setPano()，然后向其传递返回的 location.pano 字段中注明的 ID。

status 代码可能会返回以下某个值：

以下代码将创建一个 StreetViewService，它通过创建标记来响应用户在地图上的点击。用户点击该标记时，系统会显示该位置的 StreetViewPanorama。该代码会使用从服务返回的 StreetViewPanoramaData 的内容。

Maps JavaScript API 支持在 StreetViewPanorama 对象内显示自定义全景图片。您可以利用自定义全景图片显示建筑内部、景点视图或任何您想像的内容。您甚至可以将这些自定义全景图片与 Google 的现有街景全景图片链接起来。

设置一组自定义全景图像涉及下列步骤：

下文对此过程做了说明。

每幅街景全景图片都是一幅或一组图像，提供以单个位置为中心的 360 度全景视图。StreetViewPanorama 对象使用遵照等距柱状 (Plate Carrée) 投影的图像。此类投影包含 360 度水平视图（完整环绕一周）和 180 度垂直视图（从直上至直下）。这样的视野会导致图像的宽高比为 2:1。下方显示了一幅完整环绕一周的全景图片。

一般来说，要制作全景图像，您需要在一个位置拍摄多张照片，然后使用全景图片软件将这些照片拼接到一起。（如需了解详情，请参阅维基百科的照片拼接应用比较）。此类图像的“相机”位置（即拍摄每一幅全景图像的位置）应该相同。这样，生成的 360 度全景图片便可定义一个球面投影，其图像环绕在球面的二维表面上。

将全景图片视为采用直线坐标系的球面投影有助于将图像分解成直线图块，以及根据计算的图块坐标提供图像。

街景还支持利用缩放控件实现不同的图像详细程度，该控件允许您基于默认视图进行缩放。街景一般可为任何给定全景图像提供五种级别的缩放分辨率。如果您所有的缩放级别都采用一幅全景图像，那么该图像要么过大，这样会显著降低您应用的速度；要么在较高缩放级别下分辨率不佳，只能提供低像素图像。但幸运的是，我们可以在不同缩放级别下使用与提供 Google 地图图块时所用相似的设计模式，为各缩放级别下的全景图片提供分辨率适当的图像。

当 StreetViewPanorama 首次加载时，其默认显示的图像包括缩放级别为 1 的全景图片水平宽度的 25%（90 度圆弧）。此视野大致与人的正常视野一致。在此默认视野基础上“缩小”实质上是将圆弧变大，而放大则会将视野缩窄为更小的圆弧。StreetViewPanorama 会自动计算与所选缩放级别相适的视野，然后通过选择与水平视野尺寸大致相同的图块集，选择最适合该分辨率的图像。以下是视野与街景缩放级别的对应关系：

请注意，街景内显示的图像尺寸完全取决于街景容器的屏幕尺寸（宽度）。如果您提供的容器较宽，服务仍会为任何给定缩放级别提供相同的视野，但可能会改为选择更适合该分辨率的图块。

由于每一幅全景图片都包括一个等距柱状投影，因此创建全景图片图块相对容易。由于投影提供的图像宽高比为 2:1，因此具有 2:1 宽高比的图块更便于使用，但方形图块可以在方形地图上带来更好的效果（因为视野将是方形的）。

对于宽高比为 2:1 的图块，一幅囊括整个全景图片的图像代表了缩放级别为 0 的整个全景图片“世界”（基础图像），缩放级别每提高一级，zoomLevel 图块就增加 4 个。（例如，当缩放级别为 2 时，整个全景图片包括 16 个图块。）注意：街景图块处理所使用的缩放级别并不直接对应于使用街景控件时提供的缩放级别；相反，街景控件缩放级别会选择一个视野 (FoV)，然后系统再根据该视野选择合适的图块。

通常，您需要为图像图块命名，以便以编程方式选择它们。有关此类命名方案的介绍，请参阅下面的处理自定义全景图片请求。

要使用自定义全景图片，请调用 StreetViewPanorama.registerPanoProvider()，并指定自定义全景图片提供程序方法的名称。全景图片提供程序方法必须返回一个 StreetViewPanoramaData 对象，并具有以下签名：

StreetViewPanoramaData 对象的形式如下：

按如下所示显示自定义全景图片：

注意：如果您希望显示自定义全景图片，请不要直接在 StreetViewPanorama 上设置 position，因为此类位置将会指示街景服务请求靠近该位置的默认街景图像。请改为在自定义 StreetViewPanoramaData 对象的 location.latLng 字段中设置此位置。

以下示例将显示 Google 悉尼分公司的自定义全景图片。请注意，此示例未使用地图或默认街景图像：

自定义全景图片提供程序会根据所传递的全景图片 ID、缩放级别和全景图片图块坐标返回合适的图块。由于图像选择取决于这些传递的值，因此根据这些传递的值对可以编程方式选择的图像命名（如 pano_zoom_tileX_tileY.png）很有帮助。

除默认街景导航箭头外，以下示例将为图像额外添加一个箭头，该箭头指向 Google 悉尼分公司并链接到自定义图像：